---
title: OAuth integrations
description: Built-in OAuth 2.0 integrations for secure third-party service connections.
icon: key
---

## OAuth grant types

Tracecat supports two OAuth 2.0 grant types for different authentication scenarios:
- **Authorization Code Flow (Delegated User)**: OAuth flow where a human user is redirected to the provider to grant permissions.
- **Client Credentials Flow (Service Account)**: Machine to machine authentication using credentials only.

## Setup guide

Before configuring OAuth integrations in Tracecat, you must first create an OAuth application with your chosen provider (Microsoft, Google, GitHub, etc.).
This process is the same for both Authorization Code and Client Credentials flows:

1. **Create OAuth application** - Register a new application in your provider's developer console
2. **(If needed) Configure redirect URI** - Set the callback URL that Tracecat will provide during setup
3. **Obtain credentials** - Copy the client ID and client secret from your OAuth application
4. **Set permissions** - Configure the required scopes and permissions for your use case

## Managing scopes

<Note>
  Only add scopes you actually need. Extra permissions increase security risk and may require additional approval from your organization.
</Note>

OAuth integrations use a two-tier scope system:

1. **Base scopes** - Required permissions that every integration needs for basic functionality. These are automatically included and cannot be removed.
2. **Additional scopes** - Optional permissions you can add for extended functionality. Use the scope input to add custom scopes beyond the base requirements.

## Integration status

OAuth integrations have three possible states:

<Steps>
  <Step title="Not configured">
    No client credentials have been set up.
    Go into the configurations to add your client credentials.
  </Step>
  <Step title="Configured">
    Client credentials are saved but authentication hasn't been completed:
    - For Authorization Code flow, click "Connect with OAuth".
    - For Client Credentials flow, click "Test connection" or "Fetch token".
  </Step>
  <Step title="Connected">
    Successfully authenticated and ready to use in workflows. For Authorization Code flow, tokens are automatically refreshed as needed.
  </Step>
</Steps>

## Using OAuth secrets in a workflow

Unlike regular secrets, OAuth secrets are not stored in the secrets manager. Instead, they are stored in the OAuth provider's database.
You can still access them using the `SECRETS` context, but you must use the following syntax:

```php
${{ SECRETS.<provider_id>_oauth.<prefix>_[SERVICE|USER]_TOKEN }}
```

For example, to access the GitHub user token, you would use the following expression:

```php
${{ SECRETS.github_oauth.GITHUB_USER_TOKEN }}
```

When both delegated (authorization code) and service (client credentials) grants are connected, Tracecat exposes both tokens in the same provider namespace. For example, Azure Log Analytics templates can reference `${{ SECRETS.azure_log_analytics_oauth.AZURE_LOG_ANALYTICS_USER_TOKEN }}` for delegated calls or `${{ SECRETS.azure_log_analytics_oauth.AZURE_LOG_ANALYTICS_SERVICE_TOKEN }}` for service-to-service requests.

## Using OAuth secrets in UDFs

This is how you would retrieve an OAuth secret in an UDF:

```python
import requests
from tracecat_registry import RegistryOAuthSecret, registry, secrets

github_oauth_secret = RegistryOAuthSecret(
    provider_id="github",
    grant_type="authorization_code",
)

@registry.register(
    description="List repositories",
    namespace="tools.github",
    secrets=[github_oauth_secret],
)
def list_repos():
    # Retrieve the OAuth token to use
    token = secrets.get(github_oauth_secret.token_name)
    response = requests.get(
      "https://api.github.com/user/repos",
      headers={"Authorization": f"Bearer {token}"}
    )
    response.raise_for_status()
    return response.json()
```

## Using OAuth secrets in action templates

This is how you would use an OAuth secret in an action template:

```yaml
type: action
definition:
  title: List repositories
  description: List repositories from GitHub.
  display_group: GitHub
  doc_url: https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-repositories-for-the-authenticated-user
  namespace: tools.github
  name: list_repos
  secrets:
    - type: oauth
      provider_id: github
      grant_type: authorization_code
  expects:
    - ref: list_repos
      action: core.http_request
      args:
        url: https://api.github.com/user/repos
        method: GET
        headers:
          Authorization: Bearer ${{ SECRETS.github_oauth.GITHUB_USER_TOKEN }}
  returns: ${{ steps.list_repos.result.data }}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Integration shows as expired">
    OAuth tokens have limited lifespans. Tracecat automatically refreshes expired tokens using refresh tokens.

    If refresh fails, you may need to re-authorize by clicking "Connect with OAuth" again.
  </Accordion>

  <Accordion title="Scope permission errors">
    If workflows fail with permission errors, check that your integration includes the required scopes.

    You can update scopes in the configuration tab and re-authorize to grant additional permissions.
  </Accordion>

  <Accordion title="Provider connection fails">
    Verify your OAuth application configuration with the provider:
    - Redirect URI matches the one shown in Tracecat
    - Client ID and secret are correct
    - OAuth application is enabled and published
  </Accordion>
</AccordionGroup>
